Search this book | Previous | Table of contents | Next

MacHTTP configuration

This chapter instructs you how to configure MacHTTP.

The next step in understanding MacHTTP is understanding machttp.conf, the server's configuration file. The configuration file defines MacHTTP's setup. It is because the default values contained in machttp.conf are valid for 99% of MacHTTP server administrators, MacHTTP is so easy to get up and running.

The configuration file, machttp.conf, is an ASCII text file residing in the same folder as MacHTTP. You will be able to edit it with any text editor or word processing program. Which ever type of program you use, make sure your edited configuration file is saved as an ASCII text file. If you are using TeachText or SimpleText, then the file will automatically get saved as a text file. If you are using a word processor like MacWrite or WordPerfect, then you must specify in the Save dialog box that you want to save your edits as a text file. This is very important. Otherwise, MacHTTP will not be able to read its configurations and it will not run.

The format of the machttp.conf file is very simple:

  1. Each setting in machttp.conf is called a directive.
  2. Directives are case and stylistically insensitive; you can use upper- and/or lower-case letters as well as stylistic formatting in writing your directives.
  3. Any line not beginning with a directive is ignored; by convention, the hash mark (#) is used to denote comments not interpreted by MacHTTP.
  4. There can be only one directive per line.
  5. Each directive is associated with 0 or more values.

Directives, the Meat of machttp.conf

Below each of the directives are defined and examples are provided. Following that there are some sample machttp.conf files with comments and explanations.
VERSION
This is the version number of your copy of MacHTTP. After launching MacHTTP, you can read the version number in title bar. Unless you are using an older version of MacHTTP, this value should be 2.2. If the value of VERSION does not correspond with the version number of MacHTTP, then MacHTTP will complain at startup but will most likely keep running.

Examples:

  • VERSION 2.2
  • VERSION 2.01
  • VERSION 2.0.3tm

INDEX
The INDEX setting specifies the name of the default file name to search for and return to the client application when a specific file is not requested. This specification must be a simple file name and not include a path. In other words, when a client applications specifies a URL only including a folder name like http://152.1.24.177/, then MacHTTP will search and return the file in the specified folder defined by the INDEX directive.

This directive must specify a simple file name; the INDEX directive can not specify a path and therefore it should not contain any colons, the folder delimiter of path statements in the Macintosh operating system.

Examples:

  • INDEX default.html
  • INDEX index.html
  • INDEX home.html

Thus, if a client application requests the URL http:/photos/ from your computer, then MacHTTP will automatically look in the photos folder for the file specified by the INDEX setting. If the file is found, then it is returned to the client. If the file is not found, then the contents of the file specified by ERROR definition are returned.

ERROR
This directive specifies the name of an HTML file to return to the client application when it requests a folder of file that is not found on your server.

Examples:

  • ERROR :error.html
  • ERROR :file-not-found.html
  • ERROR :not-available.html

Thus, if a client application requests the URL http:/photos/chicago.gif, and the file chicago.gif is not found in the folder named photos, then MacHTTP will return to the client application the contents of the file specified in the ERROR directive. To help the readers of your server, it is a good idea to include in your ERROR file instructions on how to contact you as well as pointers to significant parts of your server.

NOACCESS
The NOACCESS directive is an HTML file returned to a client application when it tries to read from a folder or file for which it does not have permission. MacHTTP support various security features defined by the RELM and DENY directives. When somebody tries to access your server who is defined by the DENY directive, or when somebody tries to access your server who is not authorized by the RELM directive, MacHTTP will return the contents of the file specified by the NOACCESS directive.

Examples:

  • NOACCESS :noaccess.html
  • NOACCESS :access-not-allowed.html
  • NOACCESS :permission-denied.html

Like the file specified in the ERROR directive, it is a good idea to include in the NOACCESS file your name and how you can be contacted in case there seems to be a mistake as well as pointers to main aspects of your server.

LOG
The LOG directive specifies the file where a listing of who used your server and what they read is written. If no LOG directive is specified, then MacHTTP will not write to a log file.

Examples:

  • LOG :machttp.log
  • LOG :logfile.log
  • LOG :access.log

TIMEOUT
TIMEOUT is an integer specifying how long MacHTTP will wait to close a connection with a client before it considers the client application inactive. The value should be higher for slower Internet connections.

Examples:

  • TIMEOUT 60
  • TIMEOUT 30
  • TIMEOUT 90

MAXUSERS
MAXUSERS is an integer between 3 and 48, inclusive. In other words, 3 <= MAXUSERS <= 48. It specifies the maximum number of client requests MacHTTP will handle at any given time.

Examples:

  • MAXUSERS 10
  • MAXUSERS 3
  • MAXUSERS 48
  • MAXUSERS 20

The larger the value of MAXUSERS the larger amount of memory you will have to allocate to MacHTTP.

MAXLISTENS
MAXLISTENS is an integer between 3 and 48, inclusive, and not greater than the value of MAXUSERS. Expressed algebraically, MAXLISTENS <= (3 <= MAXUSERS <= 48). If your server tends to be busy (constantly receiving connections) and end-users report "Unable to connect" error messages, then this number should be closer to 48. On the other hand, the higher the value of MAXLISTENS, the more RAM must be allotted to MacHTTP. The default value is 5.

Examples:

  • MAXLISTENS 10
  • MAXLISTENS 3
  • MAXLISTENS 48
  • MAXLISTENS 5

PORT
PORT is an integer specifying the TCP/IP port where MacHTTP will "listen" for HTTP requests. Ports are like telephone number extensions where a remote computer "dials a telephone number" (computer name or IP address) and then requests services from a particular "extension" (port). Port 80 is the standard port of HTTP requests.

Examples:

  • PORT 80

It is not a good idea to change this value to anything but 80. Doing so may either create conflicts with other TCP/IP services (gopher, FTP, mail, etc.) you may have running on your server, or it will make it difficult for people to get to your server because you are not using the standard port. In short, specify PORT as 80.

PIG_DELAY
This is an integer between 0 and 120, inclusive (0 <= PIG_DELAY <= 120). When multiple programs are running on your MacHTTP server, each program allots a period of time when it will give up processing and allow other program to do some processing. This directive defines the amount of time MacHTTP will actually spend processing connections in "ticks" (60ths of a second). The number of programs you have running on your server is inversely proportional to the size of PIG_DELAY. The more programs you have running, the smaller PIG_DELAY should be. The default value is 30 (30 ticks = .5 seconds).

Examples:

  • PIG_DELAY 30
  • PIG_DELAY 45
  • PIG_DELAY 60

DUMP_BUF_SIZE
This is an integer between 256 and 10240, inclusive (256 <= DUMP_BUF_SIZE <= 10240). When transferring files to clients, MacHTTP will divide the file into pieces specified by DUMP_BUF_SIZE. If your Internet connection is slow (your server is connected to your Internet provider through a modem), then make the number smaller. If you connection is fast (your server is directly connected to the local area network), then you can make the number larger.

Examples:

  • DUMP_BUF_SIZEORT 4096
  • DUMP_BUF_SIZEORT 10240
  • DUMP_BUF_SIZEORT 256

Keep in mind, the smaller the number, the faster MacHTTP will get around to handling multiple connections, but if the number is larger, then file transfers may be speedier. Unfortunately, there seems to be no mathematical way to determine the best value for this directive. At the present time, only experimentation will prove most effective.

NO_DNS
DNS is techno-speak for "domain name services". Domain names are the alpha-numeric names given to computers on the Internet. All computers on the Internet have an Internet Protocol (IP) address, but to make the identities of Internet computer easier to remember, domain name services were created. You have seen these "domain names" before. They look like "trick.lib.ncsu.edu", "www.yahoo.com", or "sumex-aim.stanford.edu".

When a client application connects with MacHTTP, the client applications send along its IP number. When MacHTTP updates its log file (defined with the LOG directive) it can update the log with the client computer's IP address, or MacHTTP can look up the IP address and translate it into a name. Thus, you have the option to have MacHTTP do domain name service lookups or not.

Examples:

  • NO_DNS
  • #NO_DNS

Incidentally, if you include NO_DNS in your machttp.conf file, then the performance of MacHTTP will be improved because it will have less work to do. On the other hand, your log files may not be as informative as they could be.

ALLOW
This directive, as well as the following directive (DENY), provide rudimentary security features based on the client application's IP number or domain name. These directives "allow" or "deny" access to your entire server based on the identity of the client application's computer.

Follow these guidelines:

  1. The machttp.conf file can contain limitless ALLOW and DENY directives.
  2. If no ALLOW or DENY directives are included in your machttp.conf file, then the default behavior is to "allow" every client access.
  3. If there is at least one ALLOW or DENY directive, then the default behavior is to "deny" every client access unless they are defined by an ALLOW directive.
  4. IP numbers are read by MacHTTP from left to right.
  5. To ALLOW or DENY exact IP addresses, terminate the addresses with a period (.).
  6. To ALLOW or DENY a range of IP addresses, do not terminate the addresses with a period (.).
  7. Domain names are read by MacHTTP from right to left.

Examples:

  • ALLOW .com
    ALLOW .net
    ALLOW .org

In the first example above, every client would be denied access to the server except clients whose domain name ended in .com, .net, or .org. Educational institutions, as well as most of the world would not be allowed to access the server.

Examples:

  • ALLOW 152.1

In the second example, only client applications whose IP addresses began with 152.1 would be allowed to use the server. All other clients would be denied access. This example is a good one if you want to restrict access to only the people in your particular institution or department.

Examples:

  • DENY 152.1.24.177.
    ALLOW 1
    ALLOW 2
    ALLOW 3
    ALLOW 4
    ALLOW 5
    ALLOW 6
    ALLOW 7
    ALLOW 8
    ALLOW 9

In this example, the computer whose IP address is 152.1.24.177 would not be allowed access, but every other computer would be allowed access.

Examples:

  • DENY .com
    ALLOW 1
    ALLOW 2
    ALLOW 3
    ALLOW 4
    ALLOW 5
    ALLOW 6
    ALLOW 7
    ALLOW 8
    ALLOW 9

This set of DENY/ALLOW directives simply denies access to the server if and only if the client application's computer has an domain name ending in .com.

DENY
(See ALLOW above.)

REALM
Where ALLOW and DENY restrict access to your entire server based on Internet names or numbers, this directive (REALM) restricts access to sections of your server based on user names and passwords. The REALM directive is not required, and if you do not want to restrict access to sections of your server, then do not include any REALM directives. You can have any number of REALM directives in your machttp.conf file.

The format of the REALM directive is REALM <match_string> <descriptive_name> where:

  • Match_string is an alpha-numberic expression that corresponds to some section (folder) of your server's hierarchy to which you want to provide restricted access
  • Descriptive_name is a human readable name to be associated with the restricted access of your server. The descriptive_name is a realm.

In both cases, it is strongly recommended these qualifiers contain no spaces.

Once you have defined one or more realms for your server you must assign user-names and passwords to individuals who are to be granted access to those realms. This is done through the Passwords menu option of MacHTTP's Edit menu or via an AppleScript.

To assign user-names and passwords, first edit your machttp.conf file to include one or more realms. Next, launch MacHTTP. Third, choose Passwords from the Edit menu. A dialog box will be presented to you. At the bottom of the dialog box is the list of realms (descriptive_names) you have previously defined. Select a realm. Next, begin entering user-names and passwords. When you are finished, simply close the dialog box. MacHTTP will save the user-names and passwords in a file called "MacHTTP Settings" for future reference.

Examples:

  • REALM in-house employees
  • REALM very-private department
  • REALM registered-users customers

In each of the examples above, the match_strings (in-house, very-private, and registered-users) are intended to correspond to sections of your server's hierarchy. Every time a client application makes a connection with your server, MacHTTP checks to see whether or not the requested URL contains any match_strings. If it does, then MacHTTP will query the end-user for a user name and password.

Suppose a client application requested the URL http://www.shareware.com/registered-users/. This URL contains one of the match_strings from the example (registered-users). Consequently, MacHTTP would query the end-user for a user-name and password. If the user-name and password were defined in the "MacHTTP Settings" file, then the end-user would be granted access to this folder of your server. Client applications remember the user-name and password during any one session. Thus, subsequent requests for documents within a realm (http://www.shareware.com/registered-users/updates.html, for example) are handled automatically.

DEFAULT
The DEFAULT directive defines the default transfer type and MIME type for files that have no filename extension.

All filenames within your MacHTTP hierarchy are expected to have suffixes. These suffixes are suppose to unambiguously describe the format of the named file. The process of assigning filename suffixes with file formats is called "suffix mapping." When a filename does not have a suffix (example suffixes include: .txt, .html, .au, .cgi, .acgi) the DEFAULT directive takes effect. The syntax is: DEFAULT <default transfer type> <default MIME type>.

When MacHTTP is requested to deliver a file to a client, there are only two possible transfer types: BINARY and TEXT. BINARY transfers are used for files that can only be read by computers. TEXT transfers are for files that can be read by humans as well as computers. MIME types are universal file-type and encoding-type pairs describing files. MIME types originated out of the need to send files as enclosures through divergent email systems. (More about transfer and MIME types are discussed in the TEXT directive section.)

Examples:

  • DEFAULT TEXT text/html
  • DEFAULT TEXT text/plain
  • DEFAULT TEXT application/mac-binhex40
  • DEFAULT BINARY audio/x-aiff

The first example is the one that will be used by the vast majority of MacHTTP administrators. It means if a file does not have a suffix, then the file will be transferred to the client application using the TEXT transfer mode and the file is expected to be ASCII text file formatted in HTML.

The second example assumes files without suffixes are simple text files without any formatting.

The third examples assume files without suffixes are BinHex'd files and the client application should deBinHex the file once it is received.

The last example assumes files without suffixes are audio files of type aiff and should be transferred to the client application in BINARY mode.

TEXT
The TEXT directive, as well as the BINARY, CGI, ACGI, SCRIPT directives, are used to tell MacHTTP how to handle requests for files with specific filename suffixes. The syntax for each of these directives is similar:
<transfer type> <suffix> <file type> <creator> <MIME type>
where:

  • <transfer type> is either TEXT, BINARY, CGI, ACGI, or SCRIPT
  • <suffix> is a case-insensitive file name extension like .txt, .cgi, .acgi, or .aiff
  • <file type> is a four-letter, case-sensitive code used by the Macintosh operating system to describe the file types like APPL, TEXT, AIFF, or MooV. (These codes can be examined for any particular file by using ResEdit's "Get File/Folder Info..." menu command of the File menu.)
  • <creator> is a four-letter, case-sensitive code used by the Macintosh operating system to identify the application that created the file. (These codes can be examined for any particular file by using ResEdit's "Get File/Folder Info..." menu command of the File menu.)
  • <MIME type> corresponds to the same universal file-type and encoding-type pairs described in the DEFAULT directive description.

An asterisk (*) can be supplemented for the suffix, file type, or creator parameters.

When a client application requests a particular file from MacHTTP, MacHTTP can only do one of two things with the file: transfer it or run it. To determine which of these actions to take, MacHTTP relies on filename extensions or Macintosh file type/creator codes. You, as the MacHTTP administrator, tell MacHTTP how to handle various filename extensions or Macintosh file type/creator codes through the TEXT, BINARY, CGI, ACGI, and SCRIPT directives.

When MacHTTP receives are request for a file, it examines the file's suffix. If the suffix is mapped to a TEXT or BINARY directive, then the file is transmitted with the associated MIME types in text or binary mode, respectively.

On the other hand, if the suffix is mapped to a CGI, ACGI, or SCRIPT directive, then the requested file is executed and any results the cgi, acgi, or script program return are sent to the client application.

If the requested file does not have an extension, then the files Macintosh file type and creator codes are examined by MacHTTP. If those codes are mapped to the TEXT or BINARY directives, then the file is transmitted along with the associated MIME type. If the codes are mapped to the CGI, ACGI, or SCRIPT directives, then the requested file is run and any results are returned to the client.

If the requests file does not have an extension and the Macintosh file type/creator codes are not mapped to any directive, then the DEFAULT directive is used to transfer the file to the client.

(Whew!)

Examples:

  1. *TEXT .html TEXT * text/html
  2. *TEXT .text TEXT * text/plain
  3. *BINARY .gif GIFf * image/gif
  4. *CGI .cgi APPL * text/html
  5. *ACGI .acgi APPL * text/html
  6. *SCRIPT .script TEXT * text/html
  7. *SCRIPT * TEXT ToyS text/html
  8. TEXT .HTML TEXT * text/html
  9. TEXT .TEXT TEXT * text/plain
  10. TEXT .TXT TEXT * text/plain
  11. TEXT .RTF RTFf MSWD text/richtext
  12. APPL .EXE APPL * text/html
  13. SCRIPT .SCRIPT TEXT * text/html
  14. SCRIPT * TEXT ToyS text/html
  15. TEXT .HQX TEXT BNHQ application/mac-binhex40
  16. BINARY .SIT SITD * application/x-stuffit
  17. BINARY .ZIP pZIP * application/zip
  18. BINARY .au ULAW * audio/basic
  19. BINARY .AIFF * * audio/x-aiff
  20. BINARY .GIF GIFf * image/gif
  21. BINARY .PICT PICT * image/pict
  22. BINARY .JPG JPEG * image/jpeg
  23. BINARY .JPEG JPEG * image/jpeg
  24. BINARY .XBM XBMm * image/x-xbm
  25. BINARY .TIF TIFF * image/tiff
  26. BINARY .EPS EPSF * application/postscript
  27. BINARY .MOV MooV * video/quicktime
  28. BINARY .MOOV MooV * video/quicktime
  29. BINARY .MPG MPEG * video/mpeg
  30. BINARY .WORD WDBN MSWD application/msword
  31. BINARY .XL XLS3 * application/excel
  32. BINARY .XLS XLS3 * application/excel
  33. BINARY .XLS XLS4 * application/excel

BINARY
(See the TEXT directive.)

CGI
(See the TEXT directive.)

ACGI
(See the TEXT directive.)

APPL
(Do not use this directive. It is had been superseded by the CGI and ACGI directives, and it is provided for backwards compatibility only. See the TEXT directive.)

Search this book | Previous | Table of contents | Next

Eric last edited this page on September 26, 1995. Please feel free to send comments.